/*
 * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
 * ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 */

package javax.xml.ws.handler;

import javax.xml.ws.ProtocolException;
import javax.xml.ws.handler.MessageContext;

/**
 * The <code>Handler</code> interface
 * is the base interface for JAX-WS handlers.
 *
 * @since JAX-WS 2.0
 **/
public interface Handler<C extends MessageContext> {

  /**
   * The <code>handleMessage</code> method is invoked for normal processing
   * of inbound and outbound messages. Refer to the description of the handler
   * framework in the JAX-WS specification for full details.
   *
   * @param context the message context.
   * @return An indication of whether handler processing should continue for the current message
   * <ul> <li>Return <code>true</code> to continue processing.</li> <li>Return <code>false</code> to
   * block processing.</li> </ul>
   * @throws RuntimeException Causes the JAX-WS runtime to cease handler processing and generate a
   * fault.
   * @throws ProtocolException Causes the JAX-WS runtime to switch to fault message processing.
   **/
  public boolean handleMessage(C context);

  /**
   * The <code>handleFault</code> method is invoked for fault message
   * processing.  Refer to the description of the handler
   * framework in the JAX-WS specification for full details.
   *
   * @param context the message context
   * @return An indication of whether handler fault processing should continue for the current
   * message <ul> <li>Return <code>true</code> to continue processing.</li> <li>Return
   * <code>false</code> to block processing.</li> </ul>
   * @throws RuntimeException Causes the JAX-WS runtime to cease handler fault processing and
   * dispatch the fault.
   * @throws ProtocolException Causes the JAX-WS runtime to cease handler fault processing and
   * dispatch the fault.
   **/
  public boolean handleFault(C context);

  /**
   * Called at the conclusion of a message exchange pattern just prior to
   * the JAX-WS runtime dispatching a message, fault or exception.  Refer to
   * the description of the handler
   * framework in the JAX-WS specification for full details.
   *
   * @param context the message context
   **/
  public void close(MessageContext context);
}
